"""
文件操作工具模块

这个模块提供了文件和目录操作的工具类。
主要功能包括创建目录、检查路径类型等。
"""
import os
from pathlib import Path
from typing import List, Tuple


class FileUtils:
    """
    文件操作工具类
    
    提供了文件和目录操作的实用方法。
    """
    
    @staticmethod
    def ensure_dir_exists(path: str) -> None:
        """
        确保路径中的目录存在，如果不存在则创建
        
        如果输入路径是文件路径，会提取其所在目录；
        如果是目录路径，则直接使用。
        然后递归创建所有不存在的父目录。
        
        Args:
            path: 本地文件或目录的全路径
            
        示例:
            # 文件路径
            FileUtils.ensure_dir_exists('/path/to/file.txt')
            # 将创建 /path/to/ 目录
            
            # 目录路径
            FileUtils.ensure_dir_exists('/path/to/dir')
            # 将创建 /path/to/dir 目录
        """
        # 将路径转换为Path对象以便操作
        path_obj = Path(path)
        
        # 如果是文件路径，获取其父目录
        if path_obj.suffix:  # 有扩展名说明是文件
            dir_path = path_obj.parent
        else:
            dir_path = path_obj
            
        # 如果目录不存在，则创建
        if not dir_path.exists():
            try:
                dir_path.mkdir(parents=True, exist_ok=True)
            except Exception as e:
                raise IOError(f"创建目录失败: {str(e)}") 
            
    @staticmethod
    def detect_resource_type(path: str) -> str:
        """
        检测资源路径的类型
        
        根据路径的特征判断资源类型，支持以下类型：
        - FILE: 本地文件
        - FOLDER: 本地目录
        - HTTP: HTTP/HTTPS URL
        
        Args:
            path: 资源路径字符串
            
        Returns:
            str: 资源类型，可能的值: 'FILE', 'FOLDER', 'HTTP'
            
        示例:
            >>> FileUtils.detect_resource_type('/path/to/file.txt')
            'FILE'
            >>> FileUtils.detect_resource_type('/path/to/folder')
            'FOLDER'
            >>> FileUtils.detect_resource_type('https://github.com/repo')
            'HTTP'
        """
        # 检查是否是HTTP(S)链接
        if path.startswith(('http://', 'https://')):
            return 'HTTP'
        
        # 如果是本地路径
        if os.path.exists(path):
            if os.path.isfile(path):
                return 'FILE'
            elif os.path.isdir(path):
                return 'FOLDER'
            
        # 如果路径不存在，根据路径特征判断
        # 有扩展名的认为是文件
        if '.' in os.path.basename(path):
            return 'FILE'
        # 否则认为是目录
        return 'FOLDER'
            
    @staticmethod
    def write_text_to_file(file_path: str, content: str) -> None:
        """
        将文本内容写入到指定文件
        
        如果文件所在目录不存在，会自动创建。
        使用UTF-8编码写入文件。
        
        Args:
            file_path: 目标文件的完整路径
            content: 要写入的文本内容
            
        Raises:
            IOError: 当创建目录或写入文件失败时
            
        示例:
            >>> FileUtils.write_text_to_file('/path/to/file.txt', 'Hello World')
            # 将在 /path/to/file.txt 写入 'Hello World'
        """
        try:
            # 确保目录存在
            FileUtils.ensure_dir_exists(file_path)
            
            # 写入文件
            with open(file_path, 'w', encoding='utf-8') as f:
                f.write(content)
                
        except Exception as e:
            raise IOError(f"写入文件失败 {file_path}: {str(e)}")
            
